<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Migration Details Checklist: GTK+ 3 Reference Manual</title>
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
<link rel="home" href="index.html" title="GTK+ 3 Reference Manual">
<link rel="up" href="migrating.html" title="Part V. Migrating from Previous Versions of GTK+">
<link rel="prev" href="ch30s03.html" title="GtkBox versus GtkGrid: spacing">
<link rel="next" href="checklist-gdkeventexpose-region.html" title="Use GdkEventExpose.region">
<meta name="generator" content="GTK-Doc V1.33.1 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><a accesskey="u" href="migrating.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="ch30s03.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="checklist-gdkeventexpose-region.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="chapter">
<div class="titlepage"><div><div><h2 class="title">
<a name="gtk-migrating-checklist"></a>Migration Details Checklist</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="gtk-migrating-checklist.html#checklist-popup-menu">Implement GtkWidget::popup_menu</a></span></dt>
<dt><span class="section"><a href="checklist-gdkeventexpose-region.html">Use GdkEventExpose.region</a></span></dt>
<dt><span class="section"><a href="checklist-modifiers.html">Test for modifier keys correctly</a></span></dt>
<dt><span class="section"><a href="checklist-named-icons.html">Use named icons</a></span></dt>
</dl></div>
<p>
    This chapter includes a checklist of smaller things you need to do to
    ensure that your programs are good citizens in the GTK+ world.  By
    paying attention to the points in the checklist, you ensure that
    many automatic features of GTK+ will work correctly in your
    program.
  </p>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="checklist-popup-menu"></a>Implement GtkWidget::popup_menu</h2></div></div></div>
<p><b>Why. </b>
        By handling this signal, you let widgets have
        context-sensitive menus that can be invoked with the standard
        key bindings.
      </p>
<p>
      The <a class="link" href="GtkWidget.html#GtkWidget-popup-menu" title="The “popup-menu” signal"><span class="type">“popup-menu”</span></a> signal instructs the widget for which
      it is emitted to create a context-sensitive popup menu. By default,
      the key binding mechanism is set to
      emit this signal when the
      <span class="keycap"><strong>Shift</strong></span>+<span class="keycap"><strong>F10</strong></span>
      or <span class="keycap"><strong>Menu</strong></span> keys are pressed while a widget has the
      focus.  If a widget in your application shows a popup menu when
      you press a mouse button, you can make it work as well through
      the normal key binding mechanism in the following fahion:
    </p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
<p>
          Write a function to create and show a popup menu.  This
          function needs to know the button number and the event's
          time to pass them to <a class="link" href="GtkMenu.html#gtk-menu-popup" title="gtk_menu_popup ()"><code class="function">gtk_menu_popup()</code></a>.  You can implement
          such a function like this:
        </p>
<a name="do_popup_menu"></a><pre class="programlisting">
static void
do_popup_menu (GtkWidget *my_widget, GdkEventButton *event)
{
  GtkWidget *menu;
  int button, event_time;

  menu = gtk_menu_new ();
  g_signal_connect (menu, "deactivate",
                    G_CALLBACK (gtk_widget_destroy), NULL);

  /* ... add menu items ... */

  if (event)
    {
      button = event-&gt;button;
      event_time = event-&gt;time;
    }
  else
    {
      button = 0;
      event_time = gtk_get_current_event_time ();
    }

  gtk_menu_attach_to_widget (GTK_MENU (menu), my_widget, NULL);
  gtk_menu_popup (GTK_MENU (menu), NULL, NULL, NULL, NULL,
                  button, event_time);
}
        </pre>
</li>
<li class="listitem">
<p>
          In your <a class="link" href="GtkWidget.html#GtkWidget-button-press-event" title="The “button-press-event” signal"><span class="type">“button-press-event”</span></a> handler, call this function
          when you need to pop up a menu:
        </p>
<pre class="programlisting">
static gboolean
my_widget_button_press_event_handler (GtkWidget *widget, GdkEventButton *event)
{
  /* Ignore double-clicks and triple-clicks */
  if (gdk_event_triggers_context_menu ((GdkEvent *) event) &amp;&amp;
      event-&gt;type == GDK_BUTTON_PRESS)
    {
      do_popup_menu (widget, event);
      return TRUE;
    }

  return FALSE;
}
        </pre>
</li>
<li class="listitem">
<p>
          Implement a handler for the <a class="link" href="GtkWidget.html#GtkWidget-popup-menu" title="The “popup-menu” signal"><span class="type">“popup-menu”</span></a> signal:
        </p>
<pre class="programlisting">
static gboolean
my_widget_popup_menu_handler (GtkWidget *widget)
{
  do_popup_menu (widget, NULL);
  return TRUE;
}
        </pre>
</li>
</ol></div>
<div class="note"><p>
        If you do not pass a positioning function to <a class="link" href="GtkMenu.html#gtk-menu-popup" title="gtk_menu_popup ()"><code class="function">gtk_menu_popup()</code></a>,
        it will show the menu at the mouse position by default.  This
        is what you usually want when the menu is shown as a result of
        pressing a mouse button.  However, if you press the
        <span class="keycap"><strong>Shift</strong></span>+<span class="keycap"><strong>F10</strong></span>
        or <span class="keycap"><strong>Menu</strong></span> keys while the widget is focused, the
        mouse cursor may not be near the widget at all.  In the <a class="link" href="gtk-migrating-checklist.html#do_popup_menu">example above</a>, you may want to
        provide your own <a class="link" href="GtkMenu.html#GtkMenuPositionFunc" title="GtkMenuPositionFunc ()">menu-positioning function</a>
        in the case where the <em class="parameter"><code>event</code></em> is
        <code class="literal">NULL</code>.  This function should compute the desired position for
        a menu when it is invoked through the keyboard.  For example,
        <a class="link" href="GtkEntry.html" title="GtkEntry"><span class="type">GtkEntry</span></a> aligns the top edge of its popup menu with the bottom
        edge of the entry.
      </p></div>
<div class="note"><p>
        For the standard key bindings to work, your widget must be
        able to take the keyboard focus.  In general, widgets should
        be fully usable through the keyboard and not just the mouse.
        The very first step of this is to ensure that your widget
        can receive focus, using <a class="link" href="GtkWidget.html#gtk-widget-set-can-focus" title="gtk_widget_set_can_focus ()"><code class="function">gtk_widget_set_can_focus()</code></a>.
      </p></div>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.33.1</div>
</body>
</html>